<?php
/**
 * Parcl
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://parcl.com/license
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@parcl.com so we can send you a copy immediately.
 *
 * @category parcl
 * @package parcl-core
 * @copyright Copyright (c) 2006-2011 Mikael Knutsson (http://mikn.me)
 * @license http://parcl.com/license New BSD License
 * @author mikael
 */

namespace Parcl\Core {

	if(PARCL_EXEC !== 1) {
		die('<h1>Incorrect Access</h1>You cannot access this file directly.<br/>' .
			 'If you got this error message by clicking a link on the site,' .
			 'please notify the webmaster as soon as possible.');
	}

	/**
	 * Purpose     : To give the events an object with some specific functions.
	 * Description : This class specifies the single event and its functions.
	 * - Construct -
	 * Input       : $name: A string containing the Event name.
	 * Description : Binds the argument to a class variable.
	 * Errors      : No error conditions has been defined.
	 * Assumptions : That $name is a string.
	 * Dev Notes   : Should perhaps add appropriate error checks on $name, this
					 class was also created to be able to add functionality to specific
					 events, right now it isn't much though.
	 */

	class Event {
		private $name = null;

		public function __construct($name) {
			$this->name = $name;
		}

		/**
		 * Input       : None.
		 * Output      : $name: String containing the name of the specific event.
		 * Description : Returns the value of the class variable 'name'.
		 * Errors      : None.
		 * Assumptions : That $this->name is set.
		 * Dev Notes   : The assumption is a fairly sure one.
		 */

		public function GetName() {
			return $this->name;
		}

		/**
		 * Input       : None.
		 * Output      : $namespace: String containing the event namespace.
		 * Description : Gets the namespace for the specific event.
		 * Errors      : Throws an error if you try to execute this function on an
						 event without namespace.
		 * Assumptions : That $this->name is set.
		 * Dev Notes   : This function is called once per event, when the event is added
						 to the EventCollection.
		 */

		public function GetNamespace() {
			$nsPos = strpos($this->name, ':');
			if($nsPos === false) {
				throw new EventException('Tried to get namespace for an event that has none.',
										  EventException::EVENT);
			}
			$namespace = substr($this->name, 0, $nsPos);
			return $namespace;
		}

		/**
		 * Input       : $event: A variable to be checked if it is an Event object.
		 * Output      : Boolean true if it IS an Event object.
		 * Description : Checks if $event is an instance of the Event class.
		 * Errors      : Throws an error if $event isn't an instance of the class Event.
		 * Assumptions : None.
		 * Dev Notes   : This function was created to circumvent the need for type hinting
						 to control the error handling better.
		 */

		public static function IsEvent($event) {
			if(!$event instanceof Event) {
				throw new EventException('Tried to add an invalid Event to a handler ' .
										  'or trigger an event that was not added.',
										  EventException::EVENT);
			}
			return true;
		}
	}
}